Grid Topology

No matter what analysis operations you are performing on the data, visualization of the geometric elements of an unstructured grid (i.e. nodes, edges) without any data mapped to them can always be useful for a number of reasons, including but not limited to understanding the mesh topology and diagnosing patterns or issues with or prior to data analysis (e.g. analyzing the mesh of a dynamical core prior to running a simulation).

UXarray provides convenient functionality to visualize these elements of the Grid object. Below we will introduce those functions, but let us do the initial setup first:

Setup

This setup handles the package imports and data loading.

Imports

import cartopy.crs as ccrs
import geoviews.feature as gf
import holoviews as hv
import uxarray as ux

/home/runner/miniconda3/envs/cookbook-dev/lib/python3.10/site-packages/dask/dataframe/_pyarrow_compat.py:17: FutureWarning: Minimal version of pyarrow will soon be increased to 14.0.1. You are using 12.0.1. Please consider upgrading.
  warnings.warn(

Read in the data

# File paths
file_dir = "../../meshfiles/"
grid_filename = "oQU120.grid.nc"
data_filename = "oQU120.data.nc"

# A standalone grid can be opened for immediate visualization
ux_grid = ux.open_grid(file_dir + grid_filename)

# Visualization through a `UxDataset`'s associated grid, `uxds.uxgrid` is also possible.
uxds = ux.open_dataset(file_dir + grid_filename, file_dir + data_filename)

Important

How to plot through Grid, UxDataset, or UxDataArray?

As the above ux_grid and uxds creation suggests, you may either have a UxDataset (or similarly UxDataArray), or a standalone Grid object. Visualization of the geometric elements of an unstructured grid is possible in all of these cases as follows (Through uxgrid accessor when it is a UxDataset or UxDataArray):

`uxarray.Grid.plot.plotting_function()`<br />
`uxarray.UxDataset.uxgrid.plot.plotting_function()`<br />
`uxarray.UxDataArray.uxgrid.plot.plotting_function()`<br />

We will demonstrate plotting functions using the standalone ux_grid thorughout this notebook.

Plotting Edges

Plotting the edges of an Unstructured Grid gives us an immediate idea of what the actual mesh looks like since connected edges construct the faces of the grid. Because of this, edge visualization is considered as the default method for Grid topology visualization purposes, and the default plotting method uxarray.Grid.plot(), provides an edge plot as follows:

ux_grid.plot(
    title="Default Grid Plot Method",
    xlim=(-170, -50),
    ylim=(10, 80),
    width=700,
    height=350,
)

Tip

See also ux_grid.plot.mesh() and ux_grid.plot.edges() that would both create the same plot

Using `exclude_antimeridian`

The default grid plot() method as well as mesh() and edges() can take in an optional argument called exclude_antimeridian, which generates the visualization with or without correcting polygons that cross at the antimeridian (± 180 longitude):

ux_grid.plot.mesh(
    exclude_antimeridian=True,
    title="Mesh - Exclude Antimeridian Polygons",
    xlim=(-170, -50),
    ylim=(10, 80),
    width=700,
    height=350,
)

Choosing a backend

Since all of our plotting methods are built around the Holoviews package, you can select between Matplotlib and Bokeh backends if desired (Bokeh is the default and is suggested). Let us have a quick look at a Matplotlib result as well:

ux_grid.plot.edges(
    backend="matplotlib", title="Edges - Matplotlib Backend", fig_size=200
)

Plotting Nodes

The nodes (a.k.a. vertices in some unstructured mesh models) construct the corner points of faces (a.k.a. cells) in unstructured grids, hence they can also give an idea about the mesh geometry when visualized. Nodes can be visualized easily with UXarray as follows:

ux_grid.plot.nodes(
    size=1, title="Nodes", xlim=(-170, -50), ylim=(10, 80), width=700, height=350
)

Tip

See also ux_grid.plot.node_coords() that would create the same plot

Plotting Face and Edge Centers

In some cases, one might even want to visualize the center coordinates of the grid faces and edges. UXarray has functions to perform such visualizations as points:

ux_grid.plot.face_centers(
    size=1, title="Face Centers", xlim=(-170, -50), ylim=(10, 80), width=700, height=350
)

Tip

See also ux_grid.plot.face_coords() that would create the same plot

ux_grid.plot.edge_centers(
    size=1, title="Edge Centers", xlim=(-170, -50), ylim=(10, 80), width=700, height=350
)

Tip

See also ux_grid.plot.edge_coords() that would create the same plot

Putting All Together

A more meaningful visualization case could be bringing all of these plotting functions together in a single figure (This time, let’s use the uxds object to analyze its grid geometry):

(
    uxds.uxgrid.plot.edges(color="Black", line_dash="dashed", line_width=1)
    * uxds.uxgrid.plot.nodes(color="Red", size=1)
    * uxds.uxgrid.plot.face_centers(color="Blue", size=1)
    * uxds.uxgrid.plot.edge_centers(color="Green", size=1)
).opts(
    title="Node, Edge, & Face Coordinates",
    xlim=(-110, -80),
    ylim=(10, 30),
    width=700,
    height=350,
)